home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / gus / jmprotr.zip / JMPROTR.DOC next >
Text File  |  1993-03-24  |  17KB  |  412 lines
  1.         ───────────────────────────────────────────────
  2. ───────────────────────────────────────────────────────────────────────────────
  3.                        Resident JM Pro Tracker v5.0
  4.           (C) May 1992 - March 1993 by Josha Munnik from Ultra Force
  5. ───────────────────────────────────────────────────────────────────────────────
  6. ───────────────────────────────────────────────────────────────────────────────
  7. This program is public domain, meaning that you may distribute this program
  8. freely at non-commercial terms.
  9. It is not allowed to change the contents of the program in any way or
  10. to use any parts of the program for other purposes.
  11. ───────────────────────────────────────────────────────────────────────────────
  12. Contents
  13.  
  14. 1. Quickstart
  15. 2. Introduction, support & requirements.
  16. 3. Usage
  17. 4. Resident loading & errors
  18. 5. Version history
  19. 6. Player Toolbox
  20. 7. Credits & thanks
  21. ───────────────────────────────────────────────────────────────────────────────
  22. ░░░░░ 1. Quickstart ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  23. ───────────────────────────────────────────────────────────────────────────────
  24.  
  25. ■ Run 'JMPROTR' without any command line options to see a short description of
  26.   the possible options.
  27.  
  28. ■ Run 'JMPROTR *.mod' to play all MOD files in the current directory.
  29.   Add /S option for stereo output. Add /R option to load the player resident.
  30.  
  31. ■ After loading resident, run again to unload the program (possible command line
  32.   options will be ignored).
  33. ───────────────────────────────────────────────────────────────────────────────
  34. ───────────────────────────────────────────────────────────────────────────────
  35. ░░░░ 2. Introduction, support & requirements ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  36. ───────────────────────────────────────────────────────────────────────────────
  37.  
  38. Welcome to the Resident JM Pro Tracker player. An utility for playing Amiga
  39. Modules and Oktalyzer files. The player is a simple program using the command
  40. line for passing any parameters. It can be loaded resident playing files in the
  41. background.
  42.  
  43. The player supports the following sound cards :
  44.  
  45. - Gravis Ultra Sound,
  46. - Sound Blaster 16,
  47. - Sound Blaster Pro 2.0,
  48. - Sound Blaster Pro 1.0,
  49. - Sound Blaster 2.0,
  50. - Sound Blaster 1.5,
  51. - any other Sound Blaster compatible sound card.
  52.  
  53. Note : Any reference just to Sound Blaster card in this document refers to
  54.        all the Sound Blaster cards in general (1.5, 2.0, Pro 1.0, Pro 2.0, 16).
  55.        When a reference will be made to a specific kind of Sound Blaster, the
  56.        type will be mentioned.
  57.  
  58. The program will play the following music formats :
  59. - 15 instrument mod files,
  60. - 31 instrument mod file for 4 channels,
  61. - 31 instrument mod file for 6 channel produced by Triton FastTracker,
  62. - 31 instrument mod file for 8 channel produced by Triton FastTracker or
  63.   Star-Tracker,
  64. - Oktalyzer music format using 4,5,6,7,8 channels.
  65.  
  66. The player supports all Pro-Tracker effects of version 2.2A except the BPM.
  67.  
  68. This programs requires at least a 80286 processor to run with. The amount
  69. of memory needed is the size of the largest Module + 57K.
  70. ───────────────────────────────────────────────────────────────────────────────
  71. ───────────────────────────────────────────────────────────────────────────────
  72. ░░░░ 3. Usage ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  73. ───────────────────────────────────────────────────────────────────────────────
  74.  
  75. ■ Keys
  76.  
  77. The following keys can be used while playing :
  78.  
  79. - '+'. . . . . increase volume
  80. - '-'. . . . . decrease volume
  81. - Home . . . . restart at begin of song
  82. - Up . . . . . go 5 pattern-rows back (reverse)
  83. - Down . . . . go 5 pattern-rows forward
  84. - PgUp . . . . go to the start of the pattern at the next song position
  85. - PgDown . . . go to the start of the pattern at the previous song position
  86. - Escape . . . quit the player
  87. - CTRL-Break . exits the program at once.
  88. - Any other. . End the song with a volume fade. When pressing a key while fading
  89.            the song will start the next song.
  90.  
  91. If the program is loaded resident PRINT-SCREEN may be used to go to the next
  92. one in the list.
  93.  
  94. ■ Command line options
  95.  
  96.   Usage : JMPROTR options <options filename.ext [filename..] options file..>
  97.  
  98.   The command line is scanned from left to right. Two type of options are
  99.   possible :
  100.   - Main options, the last occurrence will be used.
  101.  
  102.   Example : With 'JMPROTR /P240 File.MOD File2.MOD /P220' the option /P220 will
  103.         be used.
  104.  
  105.   - File options, all song files following the option will be played using that
  106.     option.
  107.  
  108.   Example : 'JMPROTR /V32 file.mod f1.mod /V48 file3.mod /V64 file4.mod' will
  109.         play file.mod & f1.mod with main volume 32, file3.mod with main
  110.         volume 48 and file4.mod with main volume 64.
  111.  
  112. ───────────────────────────────────────────────────────────────────────────────
  113. Main options : Sound card initialisation
  114. ───────────────────────────────────────────────────────────────────────────────
  115.  
  116. ■ For Ultra Sound and Sound Blaster cards :
  117.  
  118. - /Pxx
  119.  
  120.   xx is a hexadecimal number representing the port to scan at.
  121.   Normally all possible ports are scanned starting at the lowest and ending
  122.   with the highest.
  123.   This option may be used to scan at one specific port. For example if there is
  124.   more than one sound card, this option can be used to select one of the
  125.   Sound Cards.
  126.  
  127. ■ For Sound Blaster cards :
  128.  
  129. - /Ixx
  130.  
  131.   xx is a decimal number representing the IRQ to use. At default all possible
  132.   IRQ's which may be used, are scanned.
  133.  
  134. - /Dxx . . . . . . Use DMA channel x (0,1,3) for 8 bit (/D = /D1).
  135.  
  136.   xx is a decimal number representing the DMA channel to use. At default
  137.   all possible DMA channels which may be used, are scanned.
  138.  
  139. - /Bxx . . . . . . Use DMA channel x (0,1,3,5,6,7) for 16 bit.
  140.  
  141.   Same function as /Dxx, except now it's the DMA channel for 16 bit transfers.
  142.  
  143. ───────────────────────────────────────────────────────────────────────────────
  144. Main options : Player
  145. ───────────────────────────────────────────────────────────────────────────────
  146.  
  147. ■ For Ultra Sound and Sound Blaster cards :
  148.  
  149. - /G
  150.  
  151.   This option may be used to show the patterndata being played instead
  152.   of the default output. The format of the output is as follows :
  153.  
  154. ┌────- current song position (hexadecimal)
  155. │ ┌─── current pattern number (hexadecimal)
  156. │ │ ┌─ current row in pattern (hexadecimal)
  157. ├┐├┐├┐ chan. 0chan. 1  chan. 2  chan. 3  chan. 4  chan. 5  chan. 6  chan. 7
  158. 000000║00#00000│00#00000│00#00000│00#00000│00#00000│00#00000│00#00000│00#00000║
  159.        ├┴┘├┘├┴┘
  160.        │  │ └── Effect & effect value (hexadecimal)
  161.        │  └──── Instrument number (hexadecimal)
  162.        └─────── Note, when # is shown it's the corresponding black key
  163.  
  164. - /R
  165.  
  166.   Use this option to load the player resident. After loading the player
  167.   resident, run JMPROTR again to unload the player. Any command line options
  168.   will be ignored.
  169.  
  170. - /Q
  171.  
  172.   Use Quiet mode, show no instrument information when starting a song.
  173.  
  174.  
  175. ■ For Ultra Sound, Sound Blaster Pro and Sound Blaster 16 :
  176.  
  177. - /S[+,-]
  178.  
  179.   Use stereo (/S+) or mono (/S- = default) when allowed. This option works only
  180.   on the Sound Blaster Pro, Sound Blaster 16 and UltraSound. Otherwise it
  181.   is ignored. See also /U option.
  182.  
  183. ■ For Sound Blaster cards :
  184.  
  185. - /T . . . . . . . Use timer interrupt instead of Sound Card interrupt.
  186.  
  187.   Use the timer interrupt instead of the Sound Blaster IRQ interrupt to calc
  188.   the next part. This option may result in a better sound quality. See also
  189.   the notes on running Windows when the player is loaded resident.
  190.  
  191.   Note : the timer is always used when playing on the UltraSound card.
  192.  
  193. ■ /Mxx
  194.  
  195.    Set output rate (only of use when using a Sound Blaster card).
  196.    xx is a decimal nr, which may range from 5000 to 23000 (for the Sound
  197.    Blaster 1.5) or 44100 (for the Sound Blaster 2.0, Pro & 16). Using a higher
  198.    output rate gives better sound quality but also requires more calculation
  199.    time (using a very high rate may give some sound distortion when using
  200.    a very slow computer).
  201.  
  202.    Note : When selecting a rate between 22800 and 23600 on the
  203.       Sound Blaster 16 the playspeed will slow down. This is result of
  204.       a bug in the Sound Blaster 16.
  205.  
  206. ■ /F[+,-]
  207.  
  208.   Set the mixing mode, this option is only of use on a Sound Blaster card.
  209.   At default /F+ is selected. The /F- option can be used the get a louder
  210.   output; the sound however may sound distorted, use /V option to lower the
  211.   main volume and make the distortion less.
  212.  
  213. ■ /Lxx
  214.  
  215.   Set the nr of parts to calculate in one time (xx = decimal number). A part
  216.   exists of 1/50th of a second of the output. Setting the nr of parts
  217.   to calc in one time determines the frequency at which the player will be
  218.   called. Using a higher value may result in less nr of calls in one second,
  219.   but every call in turn will take more time. This option may also be used
  220.   to create a better sound quality (by calculating more parts in one time).
  221.   This will only take place when the /T option is not used.
  222.  
  223. ───────────────────────────────────────────────────────────────────────────────
  224. File options : player
  225. ───────────────────────────────────────────────────────────────────────────────
  226.  
  227. ■ All sound cards :
  228.  
  229. - filename.ext
  230.  
  231.   An Amiga module (extensions .MOD & .NST) or an oktalyzer file. Specifying
  232.   a file which is not a module or oktalyzer file will lead to unpredictable
  233.   results (with hanging the computer as the worst). Wildcards and pathnames
  234.   are allowed. The extension are NOT used to check the kind of file so they
  235.   may differ from the ones used in this file.
  236.  
  237. - /Vxx
  238.  
  239.   xx is decimal number which specifies the main volume. The value has to
  240.   be between 0..64. The default setting is 64.
  241.  
  242. - /Nxx
  243.  
  244.    xx is a decimal number which set the nr of repeats.
  245.    The value may range from 0 to 65535, 0 is the default value.
  246.  
  247. - /Uxxxxxxxx
  248.  
  249.   Set the channel options flag. Every x stands for a channel, where the first
  250.   x is used for channel 0, the second for channel 1, etc.
  251.   The x may exist of the following chars (case-insensitive) :
  252.   - 'L'   : channel is on the left side
  253.   - 'R'   : channel is on the right side
  254.   - 'M'   : channel is on the left and right side
  255.   - 'O'   : channel is turned off
  256.  
  257.   When playing mono the 'L' & 'R' don't have effect. The 'O' has always effect.
  258.   The 'M' has only effect when playing on an UltraSound, on a Sound Blaster Pro
  259.   or Sound Blaster 16 the left side chosen.
  260.  
  261. ───────────────────────────────────────────────────────────────────────────────
  262. Examples
  263. ───────────────────────────────────────────────────────────────────────────────
  264.  
  265. ■ JMPROTR /P240 /I3 /D0 /B7 *.mod
  266.  
  267.   Scan and initialise the Sound card at port 240h, irq 3 using DMA channel 0
  268.   for 8 bit transfers and DMA channel 7 for 16 bit transfers.
  269.  
  270. ■ JMPROTR /Urrll *.mod /V32 a:*.mod /Ullmmrrmm \*.okt
  271.  
  272.   Play the .MOD files in the current directory with the first two channels
  273.   0 & 1 on the right and next two channels 2 & 3 on the left. Turn the channels
  274.   4,5,6 and 7 of (used with 6 & 8 channel modules).
  275.  
  276.   Then play the .MOD files on drive A:, using the same channel settings
  277.   and a main volume of 32.
  278.  
  279.   At last play the files *.OKT in the root directory with different channel
  280.   settings.
  281.  
  282. ■ JMPROTR /M12000 /S *.mod
  283.  
  284.   Play MOD files in the current directory with an output rate of 12.000 and
  285.   in stereo (when available).
  286.  
  287. ───────────────────────────────────────────────────────────────────────────────
  288. ───────────────────────────────────────────────────────────────────────────────
  289. ░░░░ 4. Resident loading & errors ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  290. ───────────────────────────────────────────────────────────────────────────────
  291. When loading the player resident, take the following in account :
  292.  
  293. ■ Other sound programs.
  294.  
  295.   - If you run another program which will reset the Sound Blaster or clear the
  296.     Ultra Sound memory the player will stop. It is still memory and has to be
  297.     removed in the normal way.
  298.   - Programs using only the OPL-chip, should cause no problem.
  299.  
  300. ■ MS-WINDOWS
  301.  
  302.   - If you will run MS-Windows add the /T option when loading JMPROTR
  303.     resident, otherwise it is possible the output will stop.
  304.   - The player will slow down with the Ultra Sound when running in 80386
  305.     enhanced mode. (This will be fixed in the near future.)
  306.   - See the first note when using Sound drivers for the Sound Card on which
  307.     the music is outputted.
  308.  
  309. ■ Other resident programs.
  310.  
  311.   - JMPROTR takes over several interrupts, which the program restores the
  312.     interrupts to their old state when it is removed from the memory.
  313.     So take care if you load other programs resident after loading JMPROTR.
  314. ───────────────────────────────────────────────────────────────────────────────
  315. ───────────────────────────────────────────────────────────────────────────────
  316. ░░░░ 5. Version history ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  317. ───────────────────────────────────────────────────────────────────────────────
  318.  
  319. This is version 5.0, previous versions were only distributed along the
  320. Ultra Force members for internal use and testing.
  321.  
  322. It is the successor of JMPLAYER. The name has been changed because much (if
  323. not all) has been recoded (adding effects, getting better quality).
  324. ───────────────────────────────────────────────────────────────────────────────
  325. ───────────────────────────────────────────────────────────────────────────────
  326. ░░░░ 6. Player Toolbox ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  327. ───────────────────────────────────────────────────────────────────────────────
  328.  
  329. The module & noise-tracker player used in JMPROTR is also available as a
  330. separate programmers toolbox.
  331.  
  332. Some specifications :
  333.  
  334. ■ Support for Gravis Ultra Sound, SB 1.5, SB 2.0, SB Pro 1.0, SB Pro 2.0 and
  335.   SB 16.
  336.  
  337. ■ The player allows up to 16 separate digital channels which may be put
  338.   individually on the left channel, right channel or both (the last option not
  339.   yet supported by Sound Blaster cards).
  340.  
  341.   Note : JMPROTR supports only up to 8 channels, because there's no known
  342.      format other than the MIDI format with support for 16 channels.
  343.  
  344. ■ The player is accessed using an interrupt. So it can be called in simple
  345.   manner from Pascal, C, assembly or any other programming-language with
  346.   support for interrupt calls.
  347.  
  348. ■ Either the player can be linked to the main-program using an OBJECT file or
  349.   a separate player-loader can be used. The loader will initialise the
  350.   Sound Card and reserve the required amount of memory.
  351.  
  352.   So different programs can use the player without linking the player-code to
  353.   the program. Since the player is already initialised the programs
  354.   only have to pass some info on the music data and then start the song.
  355.  
  356. ■ By using general data structures the player allows support for other file
  357.   formats than the ones mentioned in this document. There's a separate
  358.   program which contains the code for loading the module and oktalyzer files.
  359.  
  360. ■ Functions are included for following the data and changing positions
  361.   while playing.
  362.  
  363. ■ There's support for different modes for choosing between the quality of
  364.   sound and the time required by the player.
  365.  
  366. ■ The player supports all Pro-Tracker effects of version 2.2a, except the BPM.
  367.  
  368. ■ The player is completly written in fast optimized assembly code.
  369.  
  370. ■ All functions are fully documented.
  371.  
  372. ■ Interested ???? Contact Ultra Force at the following address :
  373.  
  374.                           ┌────────────────────┐
  375.               │    Ultra Force     │
  376.                           │Software Development│
  377.               │  P.O. Box 84373    │
  378.                           │ 2584 AJ The Hague  │
  379.               │  The Netherlands   │
  380.               │               │
  381.                           │Fax : +31-70-3584048│
  382.                           │BBS : +31-70-3585109│
  383.                           └────────────────────┘
  384.  
  385.   If you want a reply add a selfaddressed envelope and international stamp
  386.   order.
  387. ───────────────────────────────────────────────────────────────────────────────
  388. ───────────────────────────────────────────────────────────────────────────────
  389. ░░░░ 7. Credits & Thanks ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  390. ───────────────────────────────────────────────────────────────────────────────
  391.  
  392. I would like to thank the following persons :
  393.  
  394. ■ Tran and CyberStrike from Renaissance for making their experiences
  395.   known via UltraDox and in this way saving me a lot of debugging time.
  396.  
  397. ■ Jerry van Waardenberg, for the Beta-testing and his useful remarks.
  398.  
  399. ■ Eric Oostendorp, for the Beta-testing.
  400.  
  401. ■ Remco de Berk, for the Beta-testing and for the Ultra Sound and Sound Blaster
  402.   16 ASP.
  403.  
  404. ■ Eric Soonius, for the Beta-testing.
  405.  
  406. ■ Jeroen Koomen, for the Beta-testing.
  407.  
  408. ■ Greetings go to the other members of Ultra Force and all the Demo-groups
  409.   we know.
  410. ───────────────────────────────────────────────────────────────────────────────
  411.  
  412.